home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The 640 MEG Shareware Studio 2
/
The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO
/
pascal
/
em3270.zip
/
EM3270.DOC
next >
Wrap
Text File
|
1986-07-13
|
41KB
|
990 lines
Pascal Library Member EM3270.INC Page 1
INTRODUCTION ____________
The EM3270 procedures are the copyrighted property of Piedmont
Specialty Software. They are distributed as "Shareware" to save
the enormous costs of publishing, advertising, and distributing
software through the normal commercial channels. In keeping with
the established "rules" of this type of distribution, we ask that
you:
1. Send $20.00 to Piedmont Specialty Software, P. O. Box 6637,
Macon, GA 31208, if you find the procedures useful.
2. Use the procedures for your personal use only. If you wish
to use them in software for commercial distribution, please
contact us at the above address or by telephone at (912) 474
2318 for details of a commercial license.
3. Distribute the procedures freely, so long as you
- do not modify them,
- include this documentation with them,
- include the acompanying demonstration program.
We have used these procedures in many programs in the last two
years and have found their screen management facilities to be
well received by all users from novice to expert. We hope that
you will find them as useful and productive as we have.
Pascal Library Member EM3270.INC Page 2
I. PURPOSE
Turbo Pascal library member EM3270.INC is an INCLUDE file
containing a set of procedures which allows full-screen
editing patterned after the IBM 3270 family of terminals.
The 3270 family consists of a number of terminal models
designed to connect to the System/370 family of mainframe
processors. There are hundreds of thousands of them in use
by office workers all over the world. They operate as "full
screen I/O" terminals. That is, the mainframe sends an
entire screen at a time to the terminal, the user enters and
edits all data on the screen while "disconnected" from the
mainframe, and when finished transmits the entire modified
screen back to the mainframe by pressing one of the "atten-
tion identifier" (AID) keys.
The EM3270 procedures facilitate writing programs in Turbo
Pascal which give the user the impression that he is working
with a 3270 terminal. Then programming methods you use in
handling the screens are very different from those used by a
mainframe programmer, but the appearance to the user closely
mimics a 3270 with only a few compromises made to account
for the differences in a PC keyboard and a 3270 keyboard.
Significant features of the routines include:
a. Attribute_bytes specifying visible or invisible, bright _______________
or dim, steady or blinking characters, foreground co-
lors, and Modified Data Tags.
b. Cursor_control consisting of character right, character ______________
left, tab forward, tab backward, home cursor, and next
line.
c. Field_selection on writes and reads to and from the _______________
screen.
d. Cursor_positioning under program control before data __________________
entry.
II. USAGE
A. Program_Requirements ____________________
Before inclusion of EM3270.INC, the following statements
must appear:
{$V-}
. . .
Const
MaxFields = xxx;
Where xxx is the maximum number of data fields which can ____
appear on any screen, and is from 1 to 255. Any number of
prompt fields can appear. ______
NOTE: DO_NOT SET COMPILER DIRECTIVE {$U+} IN ANY PROGRAM NOTE: DO_NOT SET COMPILER DIRECTIVE {$U+} IN ANY PROGRAM ______ ______
USING THE EM3270 PROCEDURES. TURBO DOES STRANGE THINGS TO USING THE EM3270 PROCEDURES. TURBO DOES STRANGE THINGS TO
Pascal Library Member EM3270.INC Page 3
THE KEYBOARD BUFFER WITH THIS OPTION AND THE KEYBOARD INPUT THE KEYBOARD BUFFER WITH THIS OPTION AND THE KEYBOARD INPUT
PROCEDURES OF EM3270 BECOME FRIED. PROCEDURES OF EM3270 BECOME FRIED.
The EM3270 routines use the heap, but should not interfere
with any other heap operations of the calling program.
THE DISPOSE COMMAND IS USED IN HEAP MANAGEMENT. A CALLING _______
PROGRAM MUST NOT USE TURBO'S MARK AND RELEASE!!!!! ___
B. Initialization ______________
Before any other EM3270 procedure is executed, the EM3270 ___
system must be initialized by issuing the following command: ____
InitScreen;
This command must be issued once and only once for an execu-
tion of your program.
C. Screen_Handling_Logic _____________________
The general flow of logic in handling a screen consists of
the following sequence:
.
.
.
Procedure PresentScreen1;
Const
Strng1 : String[8] = "Prompt 1";
Strng2 : String[8] = "Prompt 2";
.
.
.
Begin
NewScreen; { clear all existing fields }
WritePrompt(1,1,Dim,8,Strng1); { write a prompt }
WritePrompt(2,1,Dim,8,Strng2); { write a prompt }
.
. { repeat for all prompts }
.
Attr := 0; {Bright, Steady, Visible, Unchanged}
WriteField(10,1,Attr,14,' ') { define field 1 }
WriteField(10,2,Attr,16,' ') { define field 2 }
.
. { repeat for all data fields }
.
End; { of procedure }
.
.
.
Procedure GetScreen1;
Begin
ReadScreen(FieldNo,FK); { open screen for input }
GetField(1,Varbl1,Attr); { retrieve a data field}
GetField(2,Varbl2,Attr); { retrieve a data field}
Pascal Library Member EM3270.INC Page 4
.
.
End; { of procedure }
.
.
Procedure RewriteScreen1;
Begin
Attr := 0;
RewriteField(1,Varbl1,Attr); { rewrite field 1 bright }
RewriteField(2,Varbl2,Attr); { rewrite field 2 bright }
.
.
.
End; { of procedure }
.
.
Begin { begin mainline program }
InitScreen; { Initialize EM3270 }
.
. { open files, etc. }
.
PresentScreen1; { write blank screen 1 }
Repeat
GetScreen1;
.
. { process screen 1 variables }
.
RewriteScreen1; { replace fields with new values }
Until Finished;
.
.
Each of the EM3270 procedures is covered in Section III.
D. Data_Fields ___________
A data field is a string which is written to the screen and ______
into which the cursor can be moved during a ReadScreen
procedure.
Every data field written to the screen is assigned a field
number from 1 to MaxFields. Data fields are numbered in the
order in which you write them to the screen. It is up to you
to keep track of what each field number contains. You always ______
address a data field by its number.
Care must be exercised in planning the sequence in which you
write data fields because cursor tabbing at program execu-
tion time is determined by field number. (This is a depar-
ture from the 3270 standard, in which the field sequence is
always left-to-right, top-to-bottom.) If the cursor is in
field 14 and the tab key pressed, it will jump to field 15,
no matter where 15 is. To keep from driving the user nuts,
screens should normally be designed so that fields are
always written in the 3270 left-to-right, top-to-bottom
Pascal Library Member EM3270.INC Page 5
sequence.
An example of when you might want to place fields out of
sequence might be a field that is almost always the same
value, but should visually appear close to some other vari-
able on the screen (state abbreviation in a local area
mailing list, for example). In such a case, you can define
it as the last screen field and provide the default value.
The cursor will skip over the field in normal tabbing, but
the user can still reach it when it needs to be changed by
tabbing until the cursor finally does reach it.
You specify the position and length of a data field
when you first write it with the WriteField procedure.
Position and length are fixed at that time and cannot be
changed afterward. When you retrieve a data field (with the
GetField procedure), the string returned is always of the
length specified when the field was first written.
You also specify the attribute of a data field when you
write it. (Attributes are discussed fully below.) The attri-
bute of a data field can be changed when you rewrite the ___
field, and its Modified Data Tag bit is automatically
changed if any data in the field is changed during a
ReadScreen procedure.
The routines DO_NOT check for a "collision" between fields. ______
If you write one field on top of another, the last field out
will be the one the user sees. However, the value of the
two fields will be maintained intact, and if you retrieve
them both you will get the correct values. The visual effect
to a user, though, is quite bizarre.
E. Prompt_Fields _____________
Prompts are strictly for the user's benefit and are treated
very different from data fields. Once written, a prompt is
forgotten - it remains on the screen, but cannot be accessed
thereafter, other than to overwrite it with another prompt
or a data field.
Prompts are not numbered and there is no limit to how many
you can write to a screen, other than the physical capacity
of the screen.
The writing of prompts and data fields may be interspersed.
Pascal Library Member EM3270.INC Page 6
F. Attributes __________
An attribute is a byte associated with a field (either data
or prompt) which defines certain characteristics of the
field. The bits of the byte are used as follows:
Bit ==> 7 6 5 4 3 2 1 0
Attribute Byte => X X X X X X X X
^ ^ ^ ^ ^ ^
0=Bright | | | | |________|
1=Dim______________| | | | |
| | | |
0=Steady | | | |
1=Blinking____________| | | |
| | |
0=Visible | | |
1=Invisible______________| | |
| |
0=Unchanged | |
1=Modified__________________| |
|
0=Use default color |
1-15=Foreground color______________|
G. Field_Appearance ________________
Original models of the 3270 could display a character in one
of two brightnesses: "normal" (dim) or "highlighted"
(bright). Later models extended this capability to include
reverse video and blinking, as well as color attributes.
The EM3270 procedures implement the attributes in one of two
ways, depending on whether they are running on a machine
with a monochrome or color monitor (the EGA is not support-
ed). The Steady/Blinking and the Visible/Invisible bits work
the same on either type.
If the Steady/Blinking bit is 0, the characters of the field
or prompt are displayed normally; if it is 1, they blink off
and on in a highly attention-grabbing (and distracting) way.
Blinking characters are normally used in rewritten fields to
call attention to a data entry error.
If the Visible/Invisible bit is 0, the characters of the
field are displayed normally; if it is 1, they are displayed
as spaces (that is, they are invisible). Moreover, any data
keyed into the field will not be displayed. The cursor moves
to the right as characters are keyed, and the characters
entered are available to your program, but the person at the
keyboard never sees them (unless you display them elsewhere
on the screen in a visible field). In the mainframe environ-
ment invisible fields are commonly used for the entry of
security passwords. Their use in the micro environment is
more limited.
Pascal Library Member EM3270.INC Page 7
On the monochrome display, the Bright/Dim bit causes the
characters of the field to be displayed in normal white on
black (Dim) when set to 1, or as inverse video (bright) when
set to 0. In the 3270, the equivalent bit simply causes the
equivalent of Turbo's LowVideo and NormVideo procedures.
However, one of the shortcomings of the original 3270 family
was that their was no easy way to show the user the length
of a data entry field. The cursor always moves into the
leftmost position of the field, but there was nothing to
show the user where the right end of the field was, and
therefore no sure indication of how many characters he could
enter before the cursor jumped to the next field. The intro-
duction of inverse video models offered a solution to this
problem and programmers quickly adopted the standard of
setting unprotected (data entry) fields to inverse. This
standard is implemented in the Bright/Dim bit in EM3270.
On the color display, the Bright/Dim bit selects one of two
background/foreground color combinations (see section I
below). This has nothing to do with the actual brightness or
dimness of the background and characters; it merely provides
a convenient way of selecting between two palettes.
The color bits of the attribute are used to override the
foreground color of the palette selected by the Bright/Dim
bit. If these four bits are 0000, the palette color is
displayed. A value of 0001 through 1111 cause the foreground
color to be the equivalent color (dark blue through white).
Note that Turbo provides predefined integer constants for
each color which can be conveniently added or ORed to an
attribute byte. For example, Attr := LightGreen will
give an attribute that will cause light green characters on
the "bright" background color. The color bits have no effect
on a monochrome monitor.
Four constants are defined in EM3270 for convenience in
working with attributes: Dim, Blinking, Invisible, Modified.
These constants facilitate such attribute setting statements
as:
Attr := Dim + Blinking + Magenta;
and attribute testing statements like:
If (Attr and Modified) <> 0 Then . . .
H. Modified_Data_Tags __________________
The modified data tag (bit 4) is normally set off (0) when a
data field is written. If the user changes any data in the
field during a ReadScreen procedure, it will be set on (1).
You can, however turn it on before writing the field and it
will stay on no matter what the user does. If the user
simply moves the cursor through a field with the cursor
control keys, the MDT will not be set. If the user deletes
Pascal Library Member EM3270.INC Page 8
or enters any data in the field, the MDT will be set, even ___
if the data is the same as the original contents. The MDT is
set or not in an invisible field exactly as for a visible
field.
I. Defining_Color_Palettes _______________________
The background and foreground colors for "bright" and "dim"
fields are controlled by setting four global variables named
BrightBG, BrightFG
DimBG, DimFG
These are of type Byte. The background colors may be set to
any of the "dark" colors, 0 (Black) through 7 (LightGray).
The foreground colors may be set to any of the 16 standard
colors, 0 (Black) through 15 (White).
These variables may be set or reset at any time and can be
used to cause some interesting effects on color screens
(they have absolutely no effect on monochrome screens). For
example, a data entry field can be written with one palette
in effect and read with another in effect by changing the
palette variables between the WriteField (or RewriteField)
and the ReadScreen procedure calls. As the user keys data
into the field, the background and foreground colors change
as each character is entered.
These variables are normally reset immediately after the
InitScreen procedure call. InitScreen sets them to white on
black for dim and black on white (inverse video) for black,
giving an approximation of the apearance of a monochrome
screen.
Note that the entire screen background color is set to the
DimBG value, so that "bright" fields appear as "islands" of
the BrightBG color in a sea of DimBG.
J. Field_Positioning _________________
The position of a data or prompt field on the screen is
specified by an "X,Y" pair of coordinate. X is the column
number on the screen and Y is the line number.
X must be from 1 to 80. Y must be from 1 to 25. The use of
line 25 is discouraged, except for brief error messages. The
procedures use the right end of line 25 to display the
Insert mode flag, and other uses for this line may be added
to EM3270 in the future. Besides, the most common models of
the 3270 don't have a 25th line.
I. Field_Length ____________
The length of a data or prompt field is specified at the
time it is written. The length must be from 1 to 79 charac-
Pascal Library Member EM3270.INC Page 9
ters.
There is no necessary connection between the length of a
string written to a field and the length of the field. A 20
character long field can be initialized with a 4 character
string (in which case 16 spaces will be added to the end of
the displayed field), or with a 100 character string (in
which case the last 80 characters will not be displayed).
However, when retrieving strings from the screen, care
should be taken to ensure that the receiving string is at
least as long as the defined screen field. Defining a 15
character screen field and then trying to read it back into
a 10 character string can cause subtle and insidious prob-
lems that would bring tears to the eyes of the most experi-
enced Turbo programmers. This flexibility (and its attendant
problems) result from the {$V-} option at the beginning of
your program.
No test is made for "line-wrap". A 20-character field writ-
ten at X position 75 will give unpredictable results.
J. AID_Keys ________
The AID keys recognized by EM3270 are the ENTER (RETURN)
key, the ESCAPE key, F1..F10, Alt/F1..Alt/F10, and
Alt/1..Alt/3. An "enumerated type" is defined at the begin-
ning of the INCLUDE file:
AID = (Enter,Escape,F1,F2,F3,F4,F5,F6,F7,F8,F9,F10,
F11,F12,F13,F14,F15,F16,F17,F18,F19,F20,
PA1,PA2,PA3);
Alt/F1..Alt/F2 map to F11..F20; Alt/1..Alt/3 map to
PA1..PA3.
You must define at least one variable of type AID to hold
the value of the AID key pressed to return control to your
program. The value of this variable may be tested for any of
its defined values with If or Case statements.
Most 3270 keyboards have more AID keys than this. 3270
keyboards have from 9 to 24 PF ("programmed function") keys,
plus ATTN, CLEAR, and a strange and seldom used one called
"Test Req". The PC keyboard's 10 function keys map nicely to
the 3270's PF1 through PF20, using the Alt key to generate
PF11 through PF20, and the Alt/1 through Alt/3 key combina-
tions map to PA1 through PA3. The RETURN key is mapped to
the 3270 ENTER key by the EM3270 procedures. The ESCAPE key
can be used to simulate the 3270's CLEAR or ATTN key at your
option. If you need more AID keys, you can modify the fol-
lowing sections of code in EM3270.INC to add them:
Pascal Library Member EM3270.INC Page 10
- The Const section of procedure ReadScreen
- The definition of type AID
- Procedure GetChar
- The last Case option in procedure ReadScreen
- The "Until" test in ReadScreen
III. PROCEDURES
A. InitScreen __________
USAGE: InitScreen; { no parameters }
This procedure has no visible affect. It merely initializes
the heap pointers to Nil, determines the monitor type, and
sets the background and foreground colors to their default
values.
THIS PROCEDURE MUST BE EXECUTED BEFORE ANY OTHER EM3270
PROCEDURE AND SHOULD BE EXECUTED ONLY ONCE!!!!!
B. NewScreen _________
USAGE: NewScreen; { no parameters }
This procedure clears and resets the screen and deletes all
fields from the heap. It should be used every time a new set
of prompts and fields is to be presented. Using ClrScr will
clear the screen, but all data fields from the previous
screen will still exist and results could be catastrophic.
C. WritePrompt ___________
USAGE: WritePrompt (X, Y, Attr, Lngth : Byte;
Strngin : ScreenLine);
X = Column number of prompt (1..79)
Y = Line number of prompt (1..25)
Attr = Atrribute for prompt
Lngth = Length of prompt field (1..79)
Strngin = Prompt literal (any string)
This procedure writes one prompt to the screen at the posi-
tion indicated by X,Y. All bits of the attribute are
effective except the Visible/Invisible bit and the Modified
Data Tag.
D. WriteField __________
USAGE: WriteField (X, Y, Attr, Lngth : Byte;
Strngin : ScreenLine);
X = Column number of data field (1..79)
Y = Line number of data field (1..25)
Attr = Atrribute for data field
Lngth = Length of data field (1..79)
Pascal Library Member EM3270.INC Page 11
Strng = Data field literal (any string)
This procedure defines and writes one data field to the
screen at the position indicated by X,Y with the character-
istics indicated by Attr. The field number is determined by
the number of executions of WriteField since the last execu-
tion of NewScreen.
E. ReadScreen __________
USAGE: ReadScreen (FieldNo : Byte;
Var FuncKey : AID);
FieldNo = Data field number in wich to initially place
the cursor
FuncKey = A variable you define in which the AID key
pressed by the user is returned
This procedure "unlocks" the keyboard for data entry. The
procedure maintains control allowing the user to enter or
erase data in any data field until an AID key is pressed.
Upon return from ReadScreen, the position of the cursor at
the time the user pressed the AID key is available in a
record named "Cursor". Its fields (all of type BYTE) are:
Cursor.Field The field number in which the cursor was
positioned.
Cursor.Char The character number within the field.
May be used to index the string returned
from the field.
Cursor.X The screen column of the cursor.
Cursor.Y The screen line of the cursor.
F. GetField ________
USAGE: GetField (FieldNo : Byte;
Var Strng : ScreenLine;
Var Attr : Byte);
FieldNo = Data field number to be retrieved
Strng = Returned string containing current value of
field. Must be at least as long as the defined
field.
Attr = Returned current attribute of data field
This procedure returns the current value of a data field. It
is normally used after a ReadScreen procedure, once for each
field to be examined.
G. RewriteField ____________
USAGE: RewriteField (FieldNo : Byte;
Strngin : ScreenLine;
Attr : Byte);
Pascal Library Member EM3270.INC Page 12
FieldNo = Data field number to be rewritten
Strng = String to be written
Attr = New attribute for field
This procedure replaces the value of a data field already on
the screen. Some occasions on which it is normally used are:
1. Displaying records from a file which the user may
change.
2. Displaying default values which may be overkeyed.
3. Rewriting a field that has failed an edit test with a
blinking or alternate color attribute.
2. The data field has been "prettied up" by editing and is
being displayed in its modified form for the benefit of
the user.
H. SetVid ______
NormVid _______
LowVid ______
USAGE SetVid (At : Byte);
NormVid (At : Byte);
LowVid (At : Byte);
At = Attribute byte
These procedures may be used to set the video mode based on
an attribute byte at any time. SetVid sets the mode based on
the entire attribute except for the Visible/Invisible bit.
NormVid and LowVid bypass the Bright/Dim bit and set the
video mode directly to "bright" or "dim" respectively, with
blink and color as specified by the attribute.
Calls to these procedures are normally made before using
Turbo's Write or WriteLn procedures to add something to an
existing screen (an error message on line 25, for instance).
You could use TextBackground and TextColor just as easily, _____
but the use of these procedures will keep your program
"attribute oriented".
IV. OPERATION
A. Cursor_Control ______________
During the ReadScreen procedure the cursor can be moved
anywhere in any data field without affecting the contents of
the fields by the use of several cursor control keys.
Cursor movements and the keys which control them are as
follows:
Pascal Library Member EM3270.INC Page 13
CURSOR RIGHT: Right Arrow. Moves the cursor one position to
the right without affecting data. if the cursor is
in the last position of a field, it jumps to the
beginning of the next field.
CURSOR LEFT: Left Arrow. Moves the cursor one position to
the left without affecting data. If the cursor is
in the first position of a field, it jumps to the
beginning of the preceding field.
TAB RIGHT: TAB key. Moves the cursor to the beginning of
the next data field without affecting data.
TAB LEFT: Shifted TAB or Backspace key. Moves the cursor to
the beginning of the preceding data field without
affecting data. The Backspace key is used because
it is in the approximate position of the Backtab
key on most 3270 keyboards. Shifted TAB is also
used, because of PC conventions.
NEW LINE: PgDn key. Moves the cursor to the beginning of
the first data field on the next line down which
contains a data field. If the cursor line is the
last such line on the screen the cursor wraps
around to the first line containing a data field.
The choice of PgDn is arbitrary, and can easily be
changed to Down Arrow or some other key. Unfortu-
nately, on most 3270 keyboards the New Line key is
in about the same position as the PC's Return
(Enter) key, and moreover is marked the same (ar-
row down and left). If the Return key were used
for New Line, there would be no appropriate key to
use for Enter. (The 3270's Enter key is about
where the PC's Caps Lock key is, except on the
3270 "data entry" keyboards, where it is located
roughly where the PC's left bracket key is. IBM
was never much good at ergonomics or consistency.)
Also, you'd think that logically the PgUp key
would jump the cursor UP one line; there is no
such key on the 3270.
HOME: The Home key returns the cursor to the first data
field on the screen.
B. Editing_Keys ____________
INSERT MODE: Ins key. In insert mode, characters typed by
the user are inserted at the cursor position,
pushing characters right until a non-blank charac-
ter is the last in the field. This is a toggle.
Pressing it again turns off insert mode. (The 3270
keyboard has a RESET key which turns off insert
mode.)
DELETE: Del key. The character at the cursor is deleted
Pascal Library Member EM3270.INC Page 14
and all characters in the field to the right are
shifted left one position. A space is shifted into
the rightmost position of the field.
ERASE EOF: End key. All characters in the data field from
the cursor position to the end of the field are
set to spaces (erased). This is another arbitrary
key choice, since there is no analogous key on the
PC.
C. Data_Entry __________
Any printable ASCII character entered ($20..$7E or ' '..'~')
will replace the character in the cursor position and turn
on the modified data tag of the field.
D. Data_Transmission _________________
When all data entry has been completed, control is returned
to the application program by pressing any of the AID keys.
V. PROBLEMS
A. One of the most common problems in using EM3270 is FORGET-
TING TO CALL INITSCREEN before the first call to one of the
other procedures. The symptoms of this are almost always a
totally "locked up" system.
B. CALLING WRITEFIELD MORE THAN MAXFIELDS TIMES will almost
always send your program into never never land.
C. FORGETTING TO CALL NEWSCREEN before writing prompts or cal-
ling WriteField will not lock up the system, but will result
in "garbage" screens and unpredictable cursor positioning.
D. OVERLAPPING FIELDS AND/OR PROMPTS are simply errors in
specifying correct X/Y values in WritePrompt and WriteField.
E. SPECIFYING A FIELD NUMBER HIGHER THAN THE HIGHEST ONE DE-
FINED in arguments to ReadScreen, RewriteField and GetField
causes unpredictable results - frequently a total system
lockup.
F. THE RETURN KEY can cause problems to people who are used to
the Teletype (and PC) standard of hitting it after each
field. It can also cause problems for some 3270 operators
since on the PC keyboard it is in the sames position as the
NEW LINE key on most 3270 keyboards. One way to get around
this is to modify the EM3270 procedures so that the RETURN
key is not one of the AID keys, but performs the same func-
tion as TAB or PgDn. Another way is to eliminate the ENTER
function through programming: every time you return from
ReadScreen with an AID value of ENTER, simply go back to
ReadScreen again with the cursor placed in the next field
(determined by adding 1 to Cursor.Field and allowing for
Pascal Library Member EM3270.INC Page 15
falling out of the last screen field). In either of these
solutions, you sacrifice the ENTER AID function and must use
only the function keys or ESCAPE to get your data.